home *** CD-ROM | disk | FTP | other *** search
/ Aminet 52 / Aminet 52 (2002)(GTI - Schatztruhe)[!][Dec 2002].iso / Aminet / dev / gg / pcre-3.9.readme < prev    next >
Text File  |  2002-09-15  |  16KB  |  350 lines
  1. Short:    Perl-compatible regular expression library
  2. Author:   Philip Hazel & Diego Casorran
  3. Uploader: dcr8520@amiga.org
  4. Version:  3.9
  5. Type:     dev/gg
  6. Requires: gcc
  7.  
  8. ----------------------------------------------------------------------------
  9.  
  10.         This  package  comes  from      http://Amiga.SourceForge.net
  11.  
  12. ----------------------------------------------------------------------------
  13.  
  14. README file for PCRE (Perl-compatible regular expression library)
  15. -----------------------------------------------------------------
  16.  
  17. The latest release of PCRE is always available from
  18.  
  19.   ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-xxx.tar.gz
  20.  
  21. Please read the NEWS file if you are upgrading from a previous release.
  22.  
  23. PCRE has its own native API, but a set of "wrapper" functions that are based on
  24. the POSIX API are also supplied in the library libpcreposix. Note that this
  25. just provides a POSIX calling interface to PCRE: the regular expressions
  26. themselves still follow Perl syntax and semantics. The header file
  27. for the POSIX-style functions is called pcreposix.h. The official POSIX name is
  28. regex.h, but I didn't want to risk possible problems with existing files of
  29. that name by distributing it that way. To use it with an existing program that
  30. uses the POSIX API, it will have to be renamed or pointed at by a link.
  31.  
  32.  
  33. Contributions by users of PCRE
  34. ------------------------------
  35.  
  36. You can find contributions from PCRE users in the directory
  37.  
  38.   ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib
  39.  
  40. where there is also a README file giving brief descriptions of what they are.
  41. Several of them provide support for compiling PCRE on various flavours of
  42. Windows systems (I myself do not use Windows). Some are complete in themselves;
  43. others are pointers to URLs containing relevant files.
  44.  
  45.  
  46. Building PCRE on a Unix system
  47. ------------------------------
  48.  
  49. To build PCRE on a Unix system, first run the "configure" command from the PCRE
  50. distribution directory, with your current directory set to the directory where
  51. you want the files to be created. This command is a standard GNU "autoconf"
  52. configuration script, for which generic instructions are supplied in INSTALL.
  53.  
  54. Most commonly, people build PCRE within its own distribution directory, and in
  55. this case, on many systems, just running "./configure" is sufficient, but the
  56. usual methods of changing standard defaults are available. For example,
  57.  
  58. CFLAGS='-O2 -Wall' ./configure --prefix=/opt/local
  59.  
  60. specifies that the C compiler should be run with the flags '-O2 -Wall' instead
  61. of the default, and that "make install" should install PCRE under /opt/local
  62. instead of the default /usr/local.
  63.  
  64. If you want to build in a different directory, just run "configure" with that
  65. directory as current. For example, suppose you have unpacked the PCRE source
  66. into /source/pcre/pcre-xxx, but you want to build it in /build/pcre/pcre-xxx:
  67.  
  68. cd /build/pcre/pcre-xxx
  69. /source/pcre/pcre-xxx/configure
  70.  
  71. If you want to make use of the experimential, incomplete support for UTF-8
  72. character strings in PCRE, you must add --enable-utf8 to the "configure"
  73. command. Without it, the code for handling UTF-8 is not included in the
  74. library. (Even when included, it still has to be enabled by an option at run
  75. time.)
  76.  
  77. The "configure" script builds five files:
  78.  
  79. . libtool is a script that builds shared and/or static libraries
  80. . Makefile is built by copying Makefile.in and making substitutions.
  81. . config.h is built by copying config.in and making substitutions.
  82. . pcre-config is built by copying pcre-config.in and making substitutions.
  83. . RunTest is a script for running tests
  84.  
  85. Once "configure" has run, you can run "make". It builds two libraries called
  86. libpcre and libpcreposix, a test program called pcretest, and the pcregrep
  87. command. You can use "make install" to copy these, the public header files
  88. pcre.h and pcreposix.h, and the man pages to appropriate live directories on
  89. your system, in the normal way.
  90.  
  91. Running "make install" also installs the command pcre-config, which can be used
  92. to recall information about the PCRE configuration and installation. For
  93. example,
  94.  
  95.   pcre-config --version
  96.  
  97. prints the version number, and
  98.  
  99.  pcre-config --libs
  100.  
  101. outputs information about where the library is installed. This command can be
  102. included in makefiles for programs that use PCRE, saving the programmer from
  103. having to remember too many details.
  104.  
  105. There is one esoteric feature that is controlled by "configure". It concerns
  106. the character value used for "newline", and is something that you probably do
  107. not want to change on a Unix system. The default is to use whatever value your
  108. compiler gives to '\n'. By using --enable-newline-is-cr or
  109. --enable-newline-is-lf you can force the value to be CR (13) or LF (10) if you
  110. really want to.
  111.  
  112.  
  113. Shared libraries on Unix systems
  114. --------------------------------
  115.  
  116. The default distribution builds PCRE as two shared libraries and two static
  117. libraries, as long as the operating system supports shared libraries. Shared
  118. library support relies on the "libtool" script which is built as part of the
  119. "configure" process.
  120.  
  121. The libtool script is used to compile and link both shared and static
  122. libraries. They are placed in a subdirectory called .libs when they are newly
  123. built. The programs pcretest and pcregrep are built to use these uninstalled
  124. libraries (by means of wrapper scripts in the case of shared libraries). When
  125. you use "make install" to install shared libraries, pcregrep and pcretest are
  126. automatically re-built to use the newly installed shared libraries before being
  127. installed themselves. However, the versions left in the source directory still
  128. use the uninstalled libraries.
  129.  
  130. To build PCRE using static libraries only you must use --disable-shared when
  131. configuring it. For example
  132.  
  133. ./configure --prefix=/usr/gnu --disable-shared
  134.  
  135. Then run "make" in the usual way. Similarly, you can use --disable-static to
  136. build only shared libraries.
  137.  
  138.  
  139. Building on non-Unix systems
  140. ----------------------------
  141.  
  142. For a non-Unix system, read the comments in the file NON-UNIX-USE. PCRE has
  143. been compiled on Windows systems and on Macintoshes, but I don't know the
  144. details because I don't use those systems. It should be straightforward to
  145. build PCRE on any system that has a Standard C compiler, because it uses only
  146. Standard C functions.
  147.  
  148.  
  149. Testing PCRE
  150. ------------
  151.  
  152. To test PCRE on a Unix system, run the RunTest script that is created by the
  153. configuring process. (This can also be run by "make runtest", "make check", or
  154. "make test".) For other systems, see the instruction in NON-UNIX-USE.
  155.  
  156. The script runs the pcretest test program (which is documented in the doc
  157. directory) on each of the testinput files (in the testdata directory) in turn,
  158. and compares the output with the contents of the corresponding testoutput file.
  159. A file called testtry is used to hold the output from pcretest. To run pcretest
  160. on just one of the test files, give its number as an argument to RunTest, for
  161. example:
  162.  
  163.   RunTest 3
  164.  
  165. The first and third test files can also be fed directly into the perltest
  166. script to check that Perl gives the same results. The third file requires the
  167. additional features of release 5.005, which is why it is kept separate from the
  168. main test input, which needs only Perl 5.004. In the long run, when 5.005 (or
  169. higher) is widespread, these two test files may get amalgamated.
  170.  
  171. The second set of tests check pcre_fullinfo(), pcre_info(), pcre_study(),
  172. pcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error
  173. detection, and run-time flags that are specific to PCRE, as well as the POSIX
  174. wrapper API. It also uses the debugging flag to check some of the internals of
  175. pcre_compile().
  176.  
  177. If you build PCRE with a locale setting that is not the standard C locale, the
  178. character tables may be different (see next paragraph). In some cases, this may
  179. cause failures in the second set of tests. For example, in a locale where the
  180. isprint() function yields TRUE for characters in the range 128-255, the use of
  181. [:isascii:] inside a character class defines a different set of characters, and
  182. this shows up in this test as a difference in the compiled code, which is being
  183. listed for checking. Where the comparison test output contains [\x00-\x7f] the
  184. test will contain [\x00-\xff], and similarly in some other cases. This is not a
  185. bug in PCRE.
  186.  
  187. The fourth set of tests checks pcre_maketables(), the facility for building a
  188. set of character tables for a specific locale and using them instead of the
  189. default tables. The tests make use of the "fr" (French) locale. Before running
  190. the test, the script checks for the presence of this locale by running the
  191. "locale" command. If that command fails, or if it doesn't include "fr" in the
  192. list of available locales, the fourth test cannot be run, and a comment is
  193. output to say why. If running this test produces instances of the error
  194.  
  195.   ** Failed to set locale "fr"
  196.  
  197. in the comparison output, it means that locale is not available on your system,
  198. despite being listed by "locale". This does not mean that PCRE is broken.
  199.  
  200. The fifth test checks the experimental, incomplete UTF-8 support. It is not run
  201. automatically unless PCRE is built with UTF-8 support. This file can be fed
  202. directly to the perltest8 script, which requires Perl 5.6 or higher. The sixth
  203. file tests internal UTF-8 features of PCRE that are not relevant to Perl.
  204.  
  205.  
  206. Character tables
  207. ----------------
  208.  
  209. PCRE uses four tables for manipulating and identifying characters. The final
  210. argument of the pcre_compile() function is a pointer to a block of memory
  211. containing the concatenated tables. A call to pcre_maketables() can be used to
  212. generate a set of tables in the current locale. If the final argument for
  213. pcre_compile() is passed as NULL, a set of default tables that is built into
  214. the binary is used.
  215.  
  216. The source file called chartables.c contains the default set of tables. This is
  217. not supplied in the distribution, but is built by the program dftables
  218. (compiled from dftables.c), which uses the ANSI C character handling functions
  219. such as isalnum(), isalpha(), isupper(), islower(), etc. to build the table
  220. sources. This means that the default C locale which is set for your system will
  221. control the contents of these default tables. You can change the default tables
  222. by editing chartables.c and then re-building PCRE. If you do this, you should
  223. probably also edit Makefile to ensure that the file doesn't ever get
  224. re-generated.
  225.  
  226. The first two 256-byte tables provide lower casing and case flipping functions,
  227. respectively. The next table consists of three 32-byte bit maps which identify
  228. digits, "word" characters, and white space, respectively. These are used when
  229. building 32-byte bit maps that represent character classes.
  230.  
  231. The final 256-byte table has bits indicating various character types, as
  232. follows:
  233.  
  234.     1   white space character
  235.     2   letter
  236.     4   decimal digit
  237.     8   hexadecimal digit
  238.    16   alphanumeric or '_'
  239.   128   regular expression metacharacter or binary zero
  240.  
  241. You should not alter the set of characters that contain the 128 bit, as that
  242. will cause PCRE to malfunction.
  243.  
  244.  
  245. Manifest
  246. --------
  247.  
  248. The distribution should contain the following files:
  249.  
  250. (A) The actual source files of the PCRE library functions and their
  251.     headers:
  252.  
  253.   dftables.c            auxiliary program for building chartables.c
  254.   get.c                 )
  255.   maketables.c          )
  256.   study.c               ) source of
  257.   pcre.c                )   the functions
  258.   pcreposix.c           )
  259.   pcre.in               "source" for the header for the external API; pcre.h
  260.                           is built from this by "configure"
  261.   pcreposix.h           header for the external POSIX wrapper API
  262.   internal.h            header for internal use
  263.   config.in             template for config.h, which is built by configure
  264.  
  265. (B) Auxiliary files:
  266.  
  267.   AUTHORS               information about the author of PCRE
  268.   ChangeLog             log of changes to the code
  269.   INSTALL               generic installation instructions
  270.   LICENCE               conditions for the use of PCRE
  271.   COPYING               the same, using GNU's standard name
  272.   Makefile.in           template for Unix Makefile, which is built by configure
  273.   NEWS                  important changes in this release
  274.   NON-UNIX-USE          notes on building PCRE on non-Unix systems
  275.   README                this file
  276.   RunTest.in            template for a Unix shell script for running tests
  277.   config.guess          ) files used by libtool,
  278.   config.sub            )   used only when building a shared library
  279.   configure             a configuring shell script (built by autoconf)
  280.   configure.in          the autoconf input used to build configure
  281.   doc/Tech.Notes        notes on the encoding
  282.   doc/pcre.3            man page source for the PCRE functions
  283.   doc/pcre.html         HTML version
  284.   doc/pcre.txt          plain text version
  285.   doc/pcreposix.3       man page source for the POSIX wrapper API
  286.   doc/pcreposix.html    HTML version
  287.   doc/pcreposix.txt     plain text version
  288.   doc/pcretest.txt      documentation of test program
  289.   doc/perltest.txt      documentation of Perl test program
  290.   doc/pcregrep.1        man page source for the pcregrep utility
  291.   doc/pcregrep.html     HTML version
  292.   doc/pcregrep.txt      plain text version
  293.   install-sh            a shell script for installing files
  294.   ltmain.sh             file used to build a libtool script
  295.   pcretest.c            comprehensive test program
  296.   pcredemo.c            simple demonstration of coding calls to PCRE
  297.   perltest              Perl test program
  298.   perltest8             Perl test program for UTF-8 tests
  299.   pcregrep.c            source of a grep utility that uses PCRE
  300.   pcre-config.in        source of script which retains PCRE information
  301.   testdata/testinput1   test data, compatible with Perl 5.004 and 5.005
  302.   testdata/testinput2   test data for error messages and non-Perl things
  303.   testdata/testinput3   test data, compatible with Perl 5.005
  304.   testdata/testinput4   test data for locale-specific tests
  305.   testdata/testinput5   test data for UTF-8 tests compatible with Perl 5.6
  306.   testdata/testinput6   test data for other UTF-8 tests
  307.   testdata/testoutput1  test results corresponding to testinput1
  308.   testdata/testoutput2  test results corresponding to testinput2
  309.   testdata/testoutput3  test results corresponding to testinput3
  310.   testdata/testoutput4  test results corresponding to testinput4
  311.   testdata/testoutput5  test results corresponding to testinput5
  312.   testdata/testoutput6  test results corresponding to testinput6
  313.  
  314. (C) Auxiliary files for Win32 DLL
  315.  
  316.   dll.mk
  317.   pcre.def
  318.  
  319. Philip Hazel <ph10@cam.ac.uk>
  320. August 2001
  321.  
  322.  
  323.  
  324.  
  325. ·············································A·r·c·h·i·v·e··C·o·n·t·e·n·t·s··
  326. LhA Freeware Version 2.2
  327. Copyright © 1991-94 by Stefan Boberg.
  328. Copyright © 1998-2000 by Jim Cooper and David Tritscher.
  329.  
  330. Listing of archive 'pcre-3.9.lha':
  331. Original  Packed Ratio    Date     Time    Name
  332. -------- ------- ----- --------- --------  -------------
  333.   481280  196982 59.0% 29-Jun-02 11:54:58  !-to-gg.tar
  334.      179     140 21.7% 02-Jan-02 15:57:56  AUTHORS
  335.    28648   11696 59.1% 02-Jan-02 15:57:56  ChangeLog
  336.     1944    1018 47.6% 02-Jan-02 15:57:56  COPYING
  337.     1944    1018 47.6% 02-Jan-02 15:57:56  LICENCE
  338.     3518    1591 54.7% 02-Jan-02 15:57:56  NEWS
  339.     2497    1259 49.5% 02-Jan-02 15:57:56  NON-UNIX-USE
  340.    14247    5202 63.4% 02-Jan-02 15:57:56  README
  341.       69      63  8.6% 31-Dec-02 23:59:58  source
  342. -------- ------- ----- --------- --------
  343.   534326  218969 59.0% Operation successful.
  344.  
  345.  
  346.  
  347.  
  348. _____________________________
  349. .Readme created with:  MRea  \
  350.